---
title: 專案結構
description: 介紹 Astro 專案基本的檔案結構。
i18nReady: true
---
import { FileTree } from '@astrojs/starlight/components'

使用 `create-astro` CLI 精靈來產生你的新 Astro 專案時，就會包含一些檔案和資料夾。至於其他項目則需要由你自己建立並加入到 Astro 既有的檔案結構。

這裡將介紹 Astro 專案是如何組織，且在你的新專案中會找到的一些檔案。

## 目錄及檔案

Astro 為你的專案準備固有的資料夾安排。每個 Astro 專案的根目錄應該包含下列目錄及檔案：

- `src/*` - 你的專案原始碼（元件、頁面、樣式、圖片等）。
- `public/*` - 你的非程式碼、未處理的資源（字體、圖示等）。
- `package.json` - 一個專案列表。
- `astro.config.mjs` - 一個 Astro 組態檔（建議）。
- `tsconfig.json` - 一個 TypeScript 組態檔（建議）。

### 範例專案樹狀圖

一個一般的 Astro 專案目錄應該看起來像這樣：

<FileTree>
- public/
  - robots.txt
  - favicon.svg
  - my-cv.pdf
- src/
    - blog/
      - post1.md
      - post2.md
      - post3.md
  - components/
    - Header.astro
    - Button.jsx
  - images/
    - image1.jpg
    - image2.jpg
    - image3.jpg
  - layouts/
    - PostLayout.astro
  - pages/
    - posts/
      - [post].astro
    - about.astro
    - **index.astro**
    - rss.xml.js
  - styles/
    - global.css
  - content.config.ts
- astro.config.mjs
- package.json
- tsconfig.json
</FileTree>

### `src/`

你大多數的專案程式碼會放在 `src/` 資料夾內，其包含了：

- [頁面](/zh-tw/basics/astro-pages/)
- [版面](/zh-tw/basics/layouts/)
- [Astro 元件](/zh-tw/basics/astro-components/)
- [前端元件（React 等）](/zh-tw/guides/framework-components/)
- [樣式 （CSS、Sass）](/zh-tw/guides/styling/)
- [Markdown](/zh-tw/guides/markdown-content/)
- [會被 Astro 處理及最佳化的圖片](/zh-tw/guides/images/)

Astro 會處理、最佳化並將你的 `src/` 捆起來建立最後瀏覽器會看到的網站。不像靜態的 `public/` 資料夾，Astro 會幫你建立並處理你 `src/` 的檔案。

一些檔案（如 Astro 元件）會被算繪成靜態的 HTML 而不會就所寫的內容傳到瀏覽器上。其他檔案（如 CSS）會被傳到瀏覽器上，但可能會為了效能表現而先被最佳化或捆進其他 CSS 檔案。

:::tip
雖然這裡提到許多 Astro 社群常見的慣例作法，但保留給 Astro 使用的目錄其實只有 `src/pages/`。你可以依照適合自己的方式，自由決定其他目錄的命名和結構。
:::

### `src/pages`

加入[支援的檔案類型](/zh-tw/basics/astro-pages/#支援的頁面檔案類型)到這個資料夾就可以建立網站的頁面路由。

:::caution
`src/pages` 在你的 Astro 專案是一個 **必須的** 子目錄。沒有它，你的網站不會有任何頁面或路由！
:::

### `src/components`

**元件** 是你 HTML 網頁中可重複使用的程式碼。它們可以是 [Astro 元件](/zh-tw/basics/astro-components/) 或是 [前端元件](/zh-tw/guides/framework-components/) 如 React 或 Vue。一般來說會在這個資料夾中組合和組織你專案所有的元件。

這是在 Astro 專案中普遍的慣例作法，但並非必須。就你自己喜好，自由自在地組織你的元件吧！

### `src/layouts`

[版面](/zh-tw/basics/layouts/)是一個 Astro 元件，用來定義由一個或多個[頁面](/zh-tw/basics/astro-pages/)共用的 UI 結構。

就如 `src/components` 一樣，這個目錄是一個普遍慣例作法並非必須。

### `src/styles`

這是一個普遍的慣例作法來儲存你的 CSS 或 Sass 檔案到一個 `src/styles` 目錄，但並非必須。只要你的樣式被存放在 `src/` 目錄內，並且有正確地匯入，Astro 就會處理並最佳化這些檔案。

### `public/`

 `public/` 目錄是放置那些在 Astro 建立過程中不需要處理的檔案和資源。這些檔案會原封不動地複製到輸出的資料夾內。

這樣的處理讓 `public/` 非常適合放置不需要任何處理的一般資源，如圖片和字體或是特殊檔案，像是 `robots.txt` 和 `manifest.webmanifest`。

你也能將 CSS 和 JavaScript 放到你的 `public/` 目錄裡，但要注意的是這些檔案在你最後輸出建立時並不會捆起來或是最佳化。

:::tip
一個原則，任何你自己寫的 CSS 或 JavaScript 應該待在你的 `src/` 目錄裡。
:::

### `package.json`

這是 JavaScript 套件管理器用來管理你依賴模組的一個檔案。它也定義了普遍會用來跑 Astro （例如： `npm run dev` 和 `npm run build` ）的腳本。

這裡有[兩種相依性](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file)你可以在 `package.json` 中指定： `dependencies` 和 `devDependencies` 。在大多情況下運作起來相同：Astro 在建立時會需要所有的相依性，而你的套件管理器會下載這兩個。我們推薦將你所有的依賴模組放在 `dependencies` 來開始，並只在你特別需要的時候才使用 `devDependencies` 。

若需要為你專案建立一個新的 `package.json` 檔案，可以看看[手動安裝](/zh-tw/install-and-setup/#手動安裝)教學來取得協助。

### `astro.config.mjs`

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的設定選項。在此你可以指定用哪些整合、建立選項、伺服選項等等。

Astro 的 JavaScript 組態檔支援幾個檔案格式：`astro.config.js`、`astro.config.mjs`、`astro.config.cjs` 以及 `astro.config.ts`。我們推薦在多數情況下使用 `.mjs`，或者如果你想要用 TypeScript 寫組態檔的話就用 `.ts`。

TypeScript 組態檔的讀取是透過 [`tsm`](https://github.com/lukeed/tsm) 處理的，並且會遵循你的專案的 tsconfig 選項。

查看[組態參考](/zh-tw/reference/configuration-reference/)來了解完整的細節。

### `tsconfig.json`

這個檔案會在每個入門範本建立且其包含了你 Astro 專案的 TypeScript 設定選項。若沒有 `tsconfig.json` 這個檔案的話，部分功能（像是 npm 軟體包匯入）在編輯器中不會被全部支援。

查看 [TypeScript 指南](/zh-tw/guides/typescript/)來了解更多設定細節。
